home *** CD-ROM | disk | FTP | other *** search
/ Windows Expert / Windows Expert.iso / desktop / spextn.zip / SPEXT.DOC < prev    next >
Text File  |  1990-06-15  |  5KB  |  150 lines
  1. Documentation for Screen Peace saver extensions.
  2.  
  3. "Saver extensions" are simply Windows DLL's that are loaded by Screen Peace.
  4. They use ".SPX" rather than ".DLL" as the file name extension.
  5.  
  6. You should compile the extension as a regular dll. Make sure to export all
  7. the routines. The export number is unimportant.
  8.  
  9.    example: sticks.def
  10.  
  11.       LIBRARY   sticks
  12.  
  13.       EXETYPE   WINDOWS
  14.  
  15.       CODE     PRELOAD MOVEABLE DISCARDABLE
  16.       DATA     PRELOAD SINGLE
  17.  
  18.       HEAPSIZE  1024
  19.  
  20.       EXPORTS
  21.          WEP           @1 RESIDENTNAME  !!! This is a standard dll routine
  22.          saverinit     @2
  23.          saverdraw     @3
  24.          saverdlgproc  @4
  25.          LibMain       @5               !!! This is a standard dll routine
  26.  
  27. The LibMain routine is called by the LibEntry routine found in the file 
  28. LIBENTRY.ASM. This file is included in the Windows 3.0 SDK as a sample file
  29. and must be linked in with the DLL. If you don't have this file, you can 
  30. write your own LibEntry routine. See the SDK documentation for more details.
  31. LibMain is declared as follows:
  32.  
  33. int FAR PASCAL LibMain(HANDLE hModule,WORD wDataSeg,WORD cbHeapSize,
  34.                        LPSTR lpszCmdLine);
  35.  
  36. The WEP routine is called by Windows when the saver DLL is unloaded. This
  37. routine should deallocate everything allocated in the LibMain routine.
  38. WEP is declared as follows:
  39.  
  40. int FAR PASCAL WEP (int bSystemExit);
  41.  
  42. In addition, the following three routines must be included in your 
  43. extension. 
  44.  
  45.  
  46. CHAR FAR * FAR PASCAL saverinit(BOOL far *enabled);
  47.  
  48.    !!! MAY BE CALLED ANY NUMBER OF TIMES SO DON'T ALLOCATE ANYTHING HERE !!!
  49.    This function is called to see if the saver is enabled and to get the
  50.    name of the saver. You must return a far pointer to a string describing
  51.    the saver if you want the saver's name displayed in the list box in the
  52.    Options dialog. Make sure to return NULL otherwise or your saver may
  53.    kill the whole Screen Peace program.
  54.  
  55.    vars:
  56.       enabled - set non-zero if the saver is enabled otherwise set to zero.
  57.  
  58.    return:
  59.       a far pointer to the name of the saver.
  60.  
  61.  
  62. BOOL FAR PASCAL saverdlgproc(HWND hdlg,unsigned message,WORD wparam,
  63.                                   LONG lparam);
  64.    
  65.    Just a regular dialog proc. This gets called when the user double clicks 
  66.    on the saver name in the Configure list box in the Options dialog. You 
  67.    should perform any user customization in this routine.
  68.  
  69.    NOTES: the Screen Peace Options dialog is both the parent and the owner
  70.           of the extension dialog.
  71.  
  72.           the return value from the dialog is not used by Screen Peace.
  73.  
  74.           DO NOT call the DefDlgProc from this dialog. Bad things will
  75.           happen.
  76.  
  77.    If you want to have a dialog, you must give the dialog resource the 
  78.    name "DIALOGBOX".
  79.  
  80.    vars:
  81.       just a regular dialog proc.
  82.  
  83. VOID FAR PASCAL saverdraw(HWND hwnd,HDC hdc,HANDLE hinst,FARPROC yieldproc);
  84.  
  85.    Called once each time the saver is invoked. This proc should consist of
  86.    a loop which first calls the yieldproc and then does any drawing. When
  87.    the yieldproc returns FALSE you should exit the loop.
  88.  
  89.    NOTES: the screen is NOT "blacked out" before the call to the saverdraw
  90.           procedure. It is the responsibility of the extension to draw
  91.           EVERYTHING.
  92.  
  93.           If you drop out of the saverdraw procedure, nothing more will be
  94.           drawn to the screen until the mouse is moved or clicked or a 
  95.           key is hit. In other words, Screen Peace does NOTHING if the
  96.           extension it selects contains a saverdraw procedure.
  97.  
  98.           The default brush for the window is guaranteed to be NULL upon
  99.           entry to saverdraw.
  100.  
  101.           It is !!!VERY IMPORTANT!!! to call the yieldproc OFTEN. Windows
  102.           is DEAD, DEAD, DEAD while you're in your loop unless you call 
  103.           this procedure. Windows will be completely locked up unless you
  104.           call this procedure.
  105.  
  106.    vars:
  107.       hwnd - the window into which you should draw.
  108.       hdc - the dc into which you should draw.
  109.       hinst - handle to instance.
  110.       yieldproc - must be called often to allow Windows to "multitask"
  111.  
  112.          yieldproc is defined as follows:
  113.  
  114.             BOOL FAR PASCAL yieldproc(VOID)
  115.  
  116.             returns TRUE if you should keep drawing or FALSE if you 
  117.             should return. This may be called AFTER it has already
  118.             returned FALSE if you need to. It will continue to return FALSE
  119.             until the saver delay time has been passed again.
  120.  
  121.  
  122. To make creating saver extensions easier, I've included a file called
  123. NEWSAVER.EXE. This creates a skeleton screen saver that is ready to compile.
  124. All it does is black out the screen. Type NEWSAVER FILENAME where
  125. FILENAME is the name you want to use for the new saver's source files.
  126. FILENAME should not include the '.' character or have any file extension.
  127.  
  128. An example screen saver extension project, STICKS, is also included because
  129. I've always found that learning by example is the best way.
  130.  
  131. How to get in touch with me:
  132.  
  133.    1. Write to:
  134.  
  135.        Anthony Andersen
  136.        1211 S. Quebec Wy #3-108
  137.        Denver, CO  80231
  138.  
  139.    2. Send Compuserve mail to:
  140.  
  141.        [72037,2474]
  142.  
  143.    3. Send mail on a BBS to:
  144.  
  145.        User # /496 - Magnum BBS     (805)582-9306
  146.        User # /74  - OS/2 Mag BBS   (805)684-0589
  147.  
  148.  
  149. 
  150.